TableTrack ApplicationIntegration Module

1. Authentication

Login to get a Bearer Token:

Request Body:

{
  "email": "user@example.com",    // required, must be valid email
  "password": "password123"        // required, string
}

Required Headers (for all requests):

2. Branch Context

Tokens are scoped to the user's restaurant and branch. To switch branches:

Request Body:

{
  "branch_id": 1    // required, integer, must exist in branches table
}

3. Catalog (POS)

Menus & Categories:

• GET /pos/menus
• GET /pos/categories

Items & Modifiers:

• GET /pos/items
• GET /pos/items/category/{id}
• GET /pos/items/menu/{id}
• GET /pos/items/{id}/variations
• GET /pos/items/{id}/modifier-groups

Order Configuration:

• GET /pos/order-types
• GET /pos/extra-charges/{orderType}
• GET /pos/delivery-platforms
• GET /pos/actions
• GET /pos/get-order-number

4. Tables & Reservations

• List tables: GET /pos/tables
• Force unlock: POST /pos/tables/{tableId}/unlock (No request body required)
• Reservations:
  • GET /pos/reservations/today
  • GET /pos/reservations
  • POST /pos/reservations
  • POST /pos/reservations/{id}/status

Create Reservation Request Body:

{
  "table_id": 1,                    // required, integer
  "reservation_date_time": "2026-01-15 19:00:00",  // required, date
  "party_size": 4,                  // required, integer, min:1
  "name": "John Doe",               // optional, string
  "phone": "+1234567890"            // optional, string
}

Update Reservation Status Request Body:

{
  "status": "confirmed"    // required, string (e.g., "pending", "confirmed", "cancelled")
}

5. Orders (POS)

• Create/Submit: POST /pos/orders
• Retrieve: GET /pos/orders or GET /pos/orders/{id}
• Update Status: POST /pos/orders/{id}/status
• Payment: POST /pos/orders/{id}/pay

Create/Submit Order Request Body:

{
  "items": [                         // required, array
    {
      "id": 1,                       // menu item id
      "quantity": 2,                 // quantity
      "price": 15.50,                // item price
      "variation_id": 5,             // optional, menu item variation id
      "modifiers": [                 // optional, array of modifiers
        {
          "id": 10,                  // modifier id
          "price": 2.00              // modifier price
        }
      ],
      "note": "Extra spicy",         // optional, item note
      "tax_amount": 1.50,            // optional
      "tax_percentage": 10,          // optional
      "tax_breakup": {}              // optional
    }
  ],
  "customer": {                      // optional, customer object
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "john@example.com"
  },
  "order_type": "Dine In",          // optional, string (default: "Dine In")
  "table_id": 5,                     // optional, integer (required for dine-in)
  "pax": 2,                          // optional, integer (default: 1)
  "waiter_id": 3,                    // optional, integer
  "delivery_address": "123 Main St", // optional, string
  "delivery_time": "2026-01-15 20:00:00",  // optional, datetime
  "delivery_fee": 5.00,              // optional, numeric (default: 0)
  "delivery_executive_id": 7,        // optional, integer
  "delivery_app_id": 2,              // optional, integer
  "customer_address_id": 10,         // optional, integer
  "discount_type": "percentage",     // optional, string
  "discount_value": 10,              // optional, numeric (default: 0)
  "discount_amount": 5.00,           // optional, numeric (default: 0)
  "taxes": [                         // optional, array
    {
      "id": 1,                       // tax id
      "amount": 2.50                 // tax amount
    }
  ],
  "extra_charges": [1, 2],           // optional, array of charge IDs or objects
  "actions": ["kot"],                // optional, array (e.g., "draft", "kot", "bill", "cancel")
  "note": "Customer special request", // optional, string
  "placed_via": "pos"                // optional, string (default: "pos")
}

Update Order Status Request Body:

{
  "status": "confirmed"    // required, string (e.g., "placed", "confirmed", "canceled")
}

Payment Request Body:

{
  "amount": 20,                      // optional, numeric
  "method": "cash|card|wallet|other" // optional, string
}

6. Customers

• List/Search: GET /pos/customers
• Create/Update: POST /pos/customers
• Phone codes: GET /pos/phone-codes

Create/Update Customer Request Body:

{
  "name": "John Doe",           // required, string, max:255
  "phone_code": "+1",           // required
  "phone": "1234567890",        // required
  "email": "john@example.com",  // optional, must be valid email
  "address": "123 Main Street"  // optional, string, max:500
}

Global customer endpoints are also available under /customer.

7. Staff, Waiters & Roles

• List by role: GET /pos/waiters?role=delivery
• Optional: include_permissions=true
• Platform endpoints:
  • GET /platform/roles
  • GET /platform/staff
  • GET /platform/permissions

Customer Addresses

• List addresses: GET /customer-addresses?customer_id={id}
• Create address: POST /customer-addresses
• Update address: PUT /customer-addresses/{id}
• Delete address: DELETE /customer-addresses/{id}

Create Customer Address Request Body:

{
  "customer_id": 1,              // required, integer
  "address": "123 Main Street",   // required, string
  "lat": 40.7128,                // optional, numeric
  "lng": -74.0060                 // optional, numeric
}

Update Customer Address Request Body:

{
  "address": "456 Oak Avenue",   // optional, string
  "lat": 40.7580,                // optional, numeric
  "lng": -73.9855                 // optional, numeric
}

Customer App Endpoints

• Get catalog: GET /customer/catalog
• Place order: POST /customer/orders
• Get my orders: GET /customer/orders?customer_id={id}

The customer app endpoints use the same request body structure as POS order endpoints. The placed_via field is automatically set to "app".

Typical POS Payment Flow

1. Create order via POST /pos/orders
2. Collect payment externally (cash, card, or gateway)
3. Confirm payment using POST /pos/orders/{id}/pay
4. Refresh orders and tables after success

Error Handling

Always include Accept: application/json header.

• 401 – Missing or invalid token
• 403 / 404 – Branch scoping violation or resource not found
• 500 – Unexpected server error

Payments must always be handled via the /pay endpoint.

Register Device Token

Request Body:

{
  "token": "fcm_or_apns_token_string",  // required, string
  "platform": "ios|android|web",       // optional, string, max:20
  "device_id": "device-123"            // optional, string, max:191
}

In-App Notifications

• List: GET /pos/notifications
• Mark as read: POST /pos/notifications/{id}/read (No request body required)
• Send test (debug): POST /pos/notifications/test

Send Test Notification Request Body:

{
  "title": "Test Notification",     // required, string
  "body": "This is a test message", // required, string
  "data": {                          // optional, object
    "order_id": 123,
    "type": "order_update"
  }
}

Broadcast (Pusher / Laravel Echo)

Channel:

Event:

Payload includes title, body, and data.